Getting Group Positions10

QuickDraw 3D provides routines that you can use to move forward and backward through the objects in a group. You do so by finding the currently occupied group positions in the group and then determining which objects occupy those positions. This section describes the routines you can use to find the valid positions in a group.

Q3Group_GetFirstPosition

You can use the Q3Group_GetFirstPosition function to get the position of the first object in a group.



 
TQ3Status Q3Group_GetFirstPosition (

                     TQ3GroupObject group, 

                     TQ3GroupPosition *position);

group: A group.
position: On exit, a group position.

DESCRIPTION

The Q3Group_GetFirstPosition function returns, in the position parameter, the position of the first object in the group specified by the group parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorNULLParameter

Q3Group_GetFirstPositionOfType

You can use the Q3Group_GetFirstPositionOfType function to get the position of the first object of a particular type in a group.



 
TQ3Status Q3Group_GetFirstPositionOfType (

                     TQ3GroupObject group, 

                     TQ3ObjectType isType, 

                     TQ3GroupPosition *position);

group: A group.
isType: An object type.
position: On exit, a group position.

DESCRIPTION

The Q3Group_GetFirstPositionOfType function returns, in the position parameter, the position of the first object in the group specified by the group parameter that has the type specified by the isType parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorNULLParameter

Q3Group_GetLastPosition

You can use the Q3Group_GetLastPosition function to get the position of the last object in a group.



 
TQ3Status Q3Group_GetLastPosition (

                     TQ3GroupObject group, 

                     TQ3GroupPosition *position);

group: A group.
position: On exit, a group position.

DESCRIPTION

The Q3Group_GetLastPosition function returns, in the position parameter, the position of the last object in the group specified by the group parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorNULLParameter

Q3Group_GetLastPositionOfType

You can use the Q3Group_GetLastPositionOfType function to get the position of the last object of a particular type in a group.



 
TQ3Status Q3Group_GetLastPositionOfType (

                     TQ3GroupObject group, 

                     TQ3ObjectType isType, 

                     TQ3GroupPosition *position);

group: A group.
isType: An object type.
position: On exit, a group position.

DESCRIPTION

The Q3Group_GetLastPositionOfType function returns, in the position parameter, the position of the last object in the group specified by the group parameter that has the type specified by the isType parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorNULLParameter

Q3Group_GetNextPosition

You can use the Q3Group_GetNextPosition function to get the position of the next object in a group.



 
TQ3Status Q3Group_GetNextPosition (

                     TQ3GroupObject group, 

                     TQ3GroupPosition *position);

group: A group.
position: On entry, a pointer to a valid group position. On exit, a pointer to the position in the specified group of the object that immediately follows the object in that position.

DESCRIPTION

The Q3Group_GetNextPosition function returns, in the position parameter, the position in the group specified by the group parameter of the object that immediately follows the object having the position specified on entry in the position parameter. If the object specified on entry is the last object in the group, Q3Group_GetNextPosition returns the value NULL in the position parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidPositionForGroup kQ3ErrorNULLParameter

Q3Group_GetNextPositionOfType

You can use the Q3Group_GetNextPositionOfType function to get the position of the next object of a particular type in a group.



 
TQ3Status Q3Group_GetNextPositionOfType (

                     TQ3GroupObject group, 

                     TQ3ObjectType isType, 

                     TQ3GroupPosition *position);

group: A group.
isType: An object type.
position: On entry, a pointer to a valid group position. On exit, a pointer to the position in the specified group of the next object that follows the object in that position and that has the specified type.

DESCRIPTION

The Q3Group_GetNextPositionOfType function returns, in the position parameter, the position in the group specified by the group parameter of the next object that follows the object having the position specified on entry in the position parameter and that has the type specified by the isType parameter. If the object specified on entry is the last object of that type in the group, Q3Group_GetNextPositionOfType returns the value NULL in the position parameter. Note that the type of the object in the position specified by the position parameter on entry to Q3Group_GetNextPositionOfType does not have to be the same as the type specified by the isType parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidPositionForGroup kQ3ErrorNULLParameter

Q3Group_GetPreviousPosition

You can use the Q3Group_GetPreviousPosition function to get the position of the previous object in a group.



 
TQ3Status Q3Group_GetPreviousPosition (

                     TQ3GroupObject group, 

                     TQ3GroupPosition *position);

group: A group.
position: On entry, a pointer to a valid group position. On exit, a pointer to the position in the specified group of the object that immediately precedes the object in that position.

DESCRIPTION

The Q3Group_GetPreviousPosition function returns, in the position parameter, the position in the group specified by the group parameter of the object that immediately precedes the object having the position specified on entry in the position parameter. If the object specified on entry is the first object in the group, Q3Group_GetPreviousPosition returns the value NULL in the position parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidPositionForGroup kQ3ErrorNULLParameter

Q3Group_GetPreviousPositionOfType

You can use the Q3Group_GetPreviousPositionOfType function to get the position of the previous object of a particular type in a group.



 
TQ3Status Q3Group_GetPreviousPositionOfType (

                     TQ3GroupObject group, 

                     TQ3ObjectType isType, 

                     TQ3GroupPosition *position);

group: A group.
isType: An object type.
position: On entry, a pointer to a valid group position. On exit, a pointer to the position in the specified group of the next object that follows the object in that position and that has the specified type.

DESCRIPTION

The Q3Group_GetPreviousPositionOfType function returns, in the position parameter, the position in the group specified by the group parameter of the previous object that precedes the object having the position specified on entry in the position parameter and that has the type specified by the isType parameter. If the object specified on entry is the first object of that type in the group, Q3Group_GetNextPositionOfType returns the value NULL in the position parameter. Note that the type of the object in the position specified by the position parameter on entry to Q3Group_GetPreviousPositionOfType does not have to be the same as the type specified by the isType parameter.

ERRORS

kQ3ErrorInvalidObject kQ3ErrorInvalidPositionForGroup kQ3ErrorNULLParameter